home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 2: Applications / Linux Cubed Series 2 - Applications.iso / editors / emacs / xemacs / xemacs-1.006 / xemacs-1 / lib / xemacs-19.13 / info / w3.info-2 < prev    next >
Encoding:
GNU Info File  |  1995-09-01  |  42.8 KB  |  1,012 lines
  1. This is Info file ../info/w3.info, produced by Makeinfo-1.63 from the
  2. input file w3.texi.
  3.  
  4.    This file documents the Emacs-w3 World Wide Web browser.
  5.  
  6.    Copyright (C) 1993, 1994, 1995 William M. Perry
  7.  
  8.    Permission is granted to make and distribute verbatim copies of this
  9. manual provided the copyright notice and this permission notice are
  10. preserved on all copies.
  11.  
  12. 
  13. File: w3.info,  Node: Action,  Next: Miscellaneous,  Prev: Information,  Up: Basic Usage
  14.  
  15. Action
  16. ======
  17.  
  18.    First, here are the keys and functions that bring up a new hypertext
  19. page, usually creating a new buffer.
  20. `return'
  21.      Pressing return when over a hyperlink attempts to follow the link
  22.      under the cursor.  With a prefix argument (`C-u'), this forces the
  23.      file to be saved to disk instead of being passed off to other
  24.      viewers or being parsed as HTML.
  25.  
  26.      Pressing return when over a form input field will prompt in the
  27.      minibuffer for the data to insert into the input field.  Type
  28.      checking is done, and the data is only entered into the form when
  29.      data of the correct type is entered (ie: you can't enter 44 for
  30.      'date' field, etc).
  31.  
  32. `button2, M-x w3-follow-mouse'
  33.      This function expects to be bound to a mouse button.  It moves to
  34.      the point under mouse and tries to fetch the link that was clicked
  35.      on.  If no link is found, a message is displayed in the minibuffer.
  36.  
  37.      Pressing return when over a form input field will prompt in the
  38.      minibuffer for the data to insert into the input field.  Type
  39.      checking is done, and the data is only entered into the form when
  40.      data of the correct type is entered (ie: you can't enter 44 for
  41.      'date' field, etc).
  42.  
  43. `C-button2, M-return, M-x w3-follow-inlined-image'
  44.      This function tries to retrieve the inlined image that is under
  45.      point.  It ignores any form entry areas or hyperlinks, and blindly
  46.      follows any inlined image.  Useful for seeing images that are
  47.      meant to be used as hyperlinks when not on a terminal capable of
  48.      displaying graphics.
  49.  
  50. `p, M-x w3-print-this-url'
  51.      Prints out the current buffer in a variety of formats, including
  52.      Postscript, HTML source, or formatted text.
  53.  
  54. `P, M-x w3-print-url-under-point'
  55.      Prints out the URL under point in a variety of formats, including
  56.      Postscript, HTML source, or formatted text.
  57.  
  58. `m, M-x w3-complete-link'
  59.      Choose from a list of all the hyperlinks in the current buffer.
  60.      Use `space' and `tab' to complete on the links.
  61.  
  62. `r, g, M-x w3-reload-document'
  63.      Reload the current document--the current buffer is killed, and the
  64.      URL it was visiting is fetched and redisplayed.  The position
  65.      within the buffer remains the same (unless the document has
  66.      changed since it was last retrieved, in which case it should be
  67.      relatively close).
  68.  
  69. `C-o, M-x w3-fetch'
  70.      This function prompts for a URL in the minibuffer, and attempts to
  71.      fetch it.  If there are any errors, or Emacs-w3 cannot understand
  72.      the type of link requested, the errors are displayed in a
  73.      hypertext buffer.
  74.  
  75. `o, M-x w3-open-local'
  76.      Find a local file, interactively.  This prompts for a local file
  77.      name to open.  The file must exist, and may be a directory.  If the
  78.      requested file is a directory and `url-use-hypertext-dired' is
  79.      `nil', then a dired-mode buffer is displayed.  If non`nil', then
  80.      Emacs-w3 automatically generates a hypertext listing of the
  81.      directory.  The hypertext mode is the default, so that all the
  82.      keys and functions remain the same.
  83.  
  84. `M-s, M-x w3-search'
  85.      Perform a search, if this is a searchable index.  This sends a
  86.      string of the type `'URL?search-terms'' to the server this
  87.      document was retrieved from.  Searching requires a server -
  88.      Emacs-w3 can not do local file searching, as there are too many
  89.      possible types of searches people could want to do.  Generally,
  90.      the only URL types that allow searching are HTTP, gopher, and
  91.      X-EXEC.
  92.  
  93. `C-c C-b, M-x w3-show-history-list'
  94.      If `url-keep-history' is non-`nil', then Emacs-w3 keeps track of
  95.      all the URLs visited in an Emacs session.  This function takes all
  96.      the links that are in that internal list, and formats them as
  97.      hypertext links in a list.
  98.  
  99.    And here are the commands to move around between Emacs-w3 buffers:
  100.  
  101. `l, M-x w3-goto-last-buffer'
  102.      Go to last WWW buffer visited
  103.  
  104. `q, M-x w3-quit'
  105.      Quits WWW mode.  This kills the current buffer and goes to the most
  106.      recently visited buffer.
  107.  
  108. `u, M-x w3-leave-buffer'
  109.      This is similar to w3-quit, but the buffer is not killed, it is
  110.      moved to the bottom of the buffer list (so it is the least likely
  111.      to show up as the default with switch-to-buffer).  This is
  112.      different from `w3-goto-last-buffer' in that it does not return to
  113.      the last WWW page visited - it is the same as using
  114.      `switch-to-buffer' - the buffer left in the window is fairly
  115.      random.
  116.  
  117. `B, M-x w3-backward-in-history'
  118.      Take one step back along the path in the current history.  Has no
  119.      effect if at the beginning of the history list.
  120.  
  121. `F, M-x w3-forward-in-history'
  122.      Take one step forward along the path in the current history.  Has
  123.      no effect if at the end of the history list.
  124.  
  125. 
  126. File: w3.info,  Node: Miscellaneous,  Prev: Action,  Up: Basic Usage
  127.  
  128. Miscellaneous
  129. =============
  130.  
  131. `M-m, M-x w3-mail-current-document'
  132.      Mails the current document to someone.  Choose from several
  133.      different formats to mail: formatted text, HTML source,
  134.      PostScript, or LaTeX source.  When the HTML source is mailed, then
  135.      an appropriate <base> tag is inserted at the beginning of the
  136.      document so that relative links may be followed correctly by
  137.      whoever receives the mail.
  138.  
  139. `M-M, M-x w3-mail-document-under-point'
  140.      Mails the document pointed to by the hypertext link under point to
  141.      someone.  Choose from several different formats to mail: formatted
  142.      text, HTML source, PostScript, or LaTeX source.  When the HTML
  143.      source is mailed, then an appropriate <base> tag is inserted at
  144.      the beginning of the document so that relative links may be
  145.      followed correctly by whoever receives the mail.
  146.  
  147. `p, M-x w3-print-this-url'
  148.      Prints the current document.  Choose from several different
  149.      formats to print: formatted text, HTML source, PostScript (with
  150.      ps-print), or by using LaTeX and dvips).
  151.  
  152.      When the formatted text is printed, the normal `lpr-buffer'
  153.      function is called, and the variables `lpr-command' and
  154.      `lpr-switches' control how the document is printed.
  155.  
  156.      When the HTML source is printed, then an appropriate <base> tag is
  157.      inserted at the beginning of the document.  When postscript is
  158.      printed, then the HTML source of the document is converted into
  159.      LaTeX source.  If the variable `w3-use-html2latex' is non-`nil',
  160.      then the program specified by `w3-html2latex-prog' is run in a
  161.      subprocess with the arguments in `w3-html2latex-args'.  The
  162.      `w3-html2latex-prog' must accept HTML source on its standard input
  163.      and send the LaTeX output to standard output.  If
  164.      `w3-use-html2latex' is `nil', then an Emacs Lisp function uses
  165.      regular expressions to replace the HTML code with LaTeX markup.
  166.      The variable `w3-latex-docstyle' controls how the document is laid
  167.      out in this case, and postscript figures are printed as well.
  168.  
  169. `P, M-x w3-print-url-under-point'
  170.      Prints the document pointed to by the hypertext link under point.
  171.      Please see the documentation for `w3-print-this-url' directly above
  172.      for more information.
  173.  
  174. `M-x w3-insert-formatted-url'
  175.      Insert a fully formatted HTML link into another buffer.  This gets
  176.      the name and URL of either the current buffer, or, with a prefix
  177.      arg, of the link under point, and construct the appropriate
  178.      <a...>...</a> markup and insert it into the desired buffer.
  179.  
  180. `M-tab, M-x w3-insert-this-url'
  181.      Inserts the URL of the current document into another buffer.
  182.      Buffer is prompted for in the minibuffer.  With prefix arg, uses
  183.      the URL of the link under point.
  184.  
  185. `U, M-x w3-use-links'
  186.      Select one of the <LINK> tags from this document and fetch it.
  187.      Links are attributes of a specific document, and can tell such
  188.      things as who made the document, where a table of contents is
  189.      located, etc.
  190.  
  191.      Link tags specify relationships between documents in two ways.
  192.      Normal (forward) relationships (where the link has a REL="xxx"
  193.      attribute), and reverse relationships (where the link has a
  194.      REV="xxx" attribute).  This first asks what type of link to follow
  195.      (Normal or Reverse), then does a `completing-read' on only the
  196.      links that have that type of relationship.
  197.  
  198. 
  199. File: w3.info,  Node: Compatibility,  Up: Top
  200.  
  201. Compatibility with Mosaic & Netscape
  202. ************************************
  203.  
  204.    Since NCSA Mosaic for Xwindows or Netscape is the de-facto hypertext
  205. browser at most sites, Emacs-w3 is compatible with them in several ways.
  206.  
  207. * Menu:
  208.  
  209. * Hotlist Handling::            A hotlist is an easy way to keep track of
  210.                 interesting Web pages without having to
  211.                 remember the exact path to get there.
  212. * Session History::             Keeping a history of documents visited
  213.                 in one Emacs sessions allows the use of
  214.                 'forward' and 'back' buttons easily.
  215. * Global History::        Keeping a history of all the places ever
  216.                 visited on the web.
  217. * Annotations::                 Annotations allow comments on other
  218.                 people's Web documents without needing
  219.                 to change the document.
  220.  
  221. 
  222. File: w3.info,  Node: Hotlist Handling,  Next: Session History,  Prev: Compatibility,  Up: Compatibility
  223.  
  224. Hotlist Handling
  225. ================
  226.  
  227.    In order to avoid having to traverse many documents to get to the
  228. same document over and over, Emacs-w3 supports a "hotlist" like Mosaic.
  229. This is a file that contains URLs and aliases.  Hotlists allow quick
  230. access to any document in the Web, providing it has been visited and
  231. added to the hotlist.  The variable `w3-hotlist-file' determines where
  232. this information is saved.  The structure of the file is compatible
  233. with Mosaic's hotlist file, so this defaults to
  234. `~/.mosaic-hotlist-default'.
  235.  
  236.    Hotlist commands are:
  237. `M-x w3-import-netscape-bookmarks'
  238.      Converts a Netscape bookmark file into Emacs-w3's internal hotlist
  239.      format.
  240.  
  241. `a, M-x w3-hotlist-add-document'
  242.      This adds the current document to the hotlist, with the buffer
  243.      name as its identifier.  Modifies the file specified by
  244.      `w3-hotlist-file'.  If this is given a PREFIX-ARGUMENT (via
  245.      `C-u'), the title is prompted for instead of automatically
  246.      defaulting to the `buffer-name'.
  247.  
  248. `M-x w3-hotlist-refresh'
  249.      This rereads the default hostlist file specified by
  250.      `w3-hotlist-file'.
  251.  
  252. `d, M-x w3-hotlist-delete'
  253.      Prompts for the alias of the entry to kill.  Pressing the spacebar
  254.      or tab will list out partial completions.  The internal
  255.      representation of the hotlist and the file specified by
  256.      `w3-hotlist-file' are updated.
  257.  
  258. `M-x w3-hotlist-rename-entry'
  259.      Some hotlist item names can be very unwieldy (`Mosaic for X level
  260.      2 fill out form support'), or uninformative (`Index of /').  If
  261.      you are not satisfied with how a specific item is labeled, you may
  262.      change it by typing `M-x w3-rename-hotlist-entry'.  Prompts for
  263.      the item to rename in the minibuffer--use the spacebar or tab key
  264.      for completion.  After having chosen an item to rename, prompts
  265.      for a new title until a unique title is entered.  Modifies the
  266.      file specified by `w3-hotlist-file'.
  267.  
  268. `H, M-x w3-use-hotlist'
  269.      Prompts for the alias to jump to.  Pressing the spacebar or tab key
  270.      shows partial completions.
  271.  
  272. `M-x w3-show-hotlist'
  273.      This converts the hotlist into HTML and displays it.
  274.  
  275. 
  276. File: w3.info,  Node: Session History,  Next: Global History,  Prev: Hotlist Handling,  Up: Compatibility
  277.  
  278. History
  279. =======
  280.  
  281.    NCSA Mosaic keeps track of the URLs followed from a page, so that it
  282. can provide forward and back buttons to keep a path of URLs that can be
  283. traversed easily.  If the variable `url-keep-history' is `t', then
  284. Emacs-w3 keeps a list of all the URLs visited in a session.  To view a
  285. listing of the history for this session of Emacs-w3, use `M-x
  286. w3-show-history' from any buffer, and Emacs-w3 generates an HTML
  287. document showing every URL visited since Emacs started (or cleared the
  288. history list), and then format it.  Any of the links can be chosen and
  289. followed to the original document.  To clear the history list, choose
  290. 'Clear History' from the 'Options' menu.
  291.  
  292.    Another twist on the history list mechanism is the fact that all
  293. Emacs-w3 buffers remember what URL, buffer, and buffer position you
  294. were at before jumping to this document, and also keeps track of where
  295. you jump to from that buffer.  This means that you can go forwards and
  296. backwards very easily along the path you took to reach a particular
  297. document.  To go forward, use the function `w3-forward-in-history', to
  298. go backward, use the function `w3-backward-in-history'.  These are
  299. fairly stable functions, but may not work as expected all the time.
  300. First, the buffer-list is used to look at the URL of every buffer, and
  301. if it matches the item in the history list you are looking for, then it
  302. is brought forward.  If no buffer containing the desired URL is found,
  303. then the URL is fetched.  Then the desired position in the buffer is
  304. searched for.
  305.  
  306. 
  307. File: w3.info,  Node: Global History,  Next: Annotations,  Prev: Session History,  Up: Compatibility
  308.  
  309. Global History
  310. ==============
  311.  
  312.    Mosaic and Netscape supports the idea of a "history" of URLs the
  313. user has visited, and it displays them in a different style than normal
  314. URLs.  If the variable `url-keep-history' is `t', then Emacs-w3 keeps a
  315. list of all the URLs visited in a session.  The file is automatically
  316. written to disk when exiting emacs.  The list is added to those already
  317. in the file specified by `url-global-history-file', which defaults to
  318. `~/.mosaic-global-history'.
  319.  
  320.    If any URL in the list is found in the file, it is not saved, but new
  321. ones are added at the end of the file.
  322.  
  323.    The function that saves the global history list is smart enough to
  324. notice what style of history list you are using (Netscape or XMosaic),
  325. and writes out the new additions appropriately.
  326.  
  327.    One of the nice things about keeping a global history files is that
  328. Emacs-w3 can use it as a completion table.  When doing `M-x w3-fetch',
  329. pressing the `tab' or `space' keys will show all completions for a
  330. partial URL.  This is very useful, especially for very long URLs that
  331. are not in a hotlist, or for seeing all the pages from a particular web
  332. server before choosing which to retrieve.
  333.  
  334. 
  335. File: w3.info,  Node: Annotations,  Next: Group Annotations,  Prev: Global History,  Up: Compatibility
  336.  
  337. Annotations
  338. ===========
  339.  
  340.    Mosaic can annotate documents.  Annotations are comments about the
  341. current document, and these annotations appear as a link to the
  342. comments at the end of the document when you browse it in Mosaic.  The
  343. original file is not changed.  There are two types of annotations
  344. supported in Mosaic, and both are supported by Emacs-w3 as well.
  345.  
  346. * Menu:
  347.  
  348. * Group Annotations::             Annotations accessible by everyone
  349. * Personal Annotations::          Private annotations only accessible
  350.                   to the user who created them
  351.  
  352. 
  353. File: w3.info,  Node: Group Annotations,  Next: Personal Annotations,  Prev: Annotations,  Up: Annotations
  354.  
  355. Group Annotations
  356. -----------------
  357.  
  358.    NOTE: The group annotation experiment has been terminated.  It will
  359. be replaced with support on the server side for adding <LINK> tags to
  360. documents.
  361.  
  362. 
  363. File: w3.info,  Node: Personal Annotations,  Prev: Group Annotations,  Up: Annotations
  364.  
  365. Personal Annotations
  366. --------------------
  367.  
  368.    If you do not want to share your musings about a particular document
  369. with the entire network, you can add a personal annotation that only you
  370. can see.  Personal annotations are stored in a subdirectory in the users
  371. account on the local disk, with a log file that contains information
  372. about what URLs have been annotated and which files contain the
  373. annotations.
  374.  
  375.    Emacs-w3 looks in the directory specified by
  376. `w3-personal-annotation-directory' (defaults to
  377. `~/.mosaic-personal-annotations').  Any personal annotations for a
  378. document are automatically appended when it is retrieved.
  379.  
  380.    To add a new personal annotation, type `M-x
  381. w3-add-personal-annotation'.  This creates a new buffer, in the mode
  382. specified by `w3-annotation-mode'.  This defaults to `html-mode'.  If
  383. this variable is `nil', or it points to an undefined function, then
  384. `default-major-mode' is consulted.
  385.  
  386.    A minor mode redefines `C-c C-c' to complete the annotation and
  387. store it on the local disk.
  388.  
  389.    To delete a personal annotation, it must be the current page.  Once
  390. reading the annotation, `M-x w3-delete-personal-annotation' will remove
  391. it.  This deletes the file containing the annotation, and any
  392. references to it in the annotation log file.
  393.  
  394.    Editing personal annotations is not yet supported.
  395.  
  396. 
  397. File: w3.info,  Node: Controlling Formatting,  Next: General Formatting,  Prev: Top,  Up: Top
  398.  
  399. Controlling Formatting
  400. **********************
  401.  
  402.    How Emacs-w3 formats a document is very customizable.  How a
  403. document is displayed depends on whether the user is on a terminal
  404. capable of graphics and a few variables.
  405.  
  406.    The following sections describe in more detail how to change the
  407. formatting of a document.
  408.  
  409. * Menu:
  410.  
  411. * General Formatting::                 Changing general things about a
  412.                                        document.
  413. * Character based terminals::          Changing how a document is
  414.                                        displayed on a non-graphics
  415.                                        terminal (vt100, etc.) or if
  416.                                        `w3-delimit-emphasis' is `t'.
  417. * Smart terminals::                    Getting highlighting of links, etc.
  418.                                        on not-quite-so-dumb terminals (vt100s
  419.                                        and comparable machines)
  420. * Graphics workstations::              Changing how a document is
  421.                                        displayed on a graphics terminal
  422.                                        (Xwindows, Windows, NeXTstep,
  423.                                        OS/2, etc.)
  424. * Inlined images::                     How to specify how Emacs-w3
  425.                                        handles inlined images/mpegs.
  426.  
  427. 
  428. File: w3.info,  Node: General Formatting,  Next: Character based terminals,  Prev: Controlling Formatting,  Up: Controlling Formatting
  429.  
  430. General formatting conventions
  431. ==============================
  432.  
  433.                           -------------------
  434.  
  435.                         Setting the fill column
  436.  
  437.                           -------------------
  438.  
  439.    Each time a document is parsed, the `fill-column' is recalculated
  440. using `window-width' and `w3-right-border'.  `w3-right-border' is an
  441. integer specifying how much room at the right edge of the screen to
  442. leave blank.  The `fill-column' is set to `(- (window-width)
  443. `w3-right-border')'.
  444.  
  445.                           -------------------
  446.  
  447.                      Formatting of hypertext links
  448.  
  449.                           -------------------
  450.  
  451.    If the variable `w3-delimit-links' is non-`nil' (the default for
  452. text-terminals), then hypertext links are surrounded by text specified
  453. by the user.  The variables `w3-link-start-delimiter' and
  454. `w3-link-end-delimiter' control what text is at the start and end of a
  455. hypertext link.  These variables are cons-pairs of two strings.
  456.  
  457.    If a link has never been visited before (it is not in the global
  458. history), then the `car' of these variables is inserted at the start
  459. and end of the link.  If the link has been visited before, then the
  460. `cdr' is inserted.  So, links look like:
  461.  
  462.      [[This is a hypertext link]] that has never been visited.
  463.      {{This one, however}} has been seen before at some point in time.
  464.  
  465.                           -------------------
  466.  
  467.                           Formatting of lists
  468.  
  469.                           -------------------
  470.  
  471.    There are several different ways to control the formatting of lists.
  472. The most obvious is how deeply they are indented relative to the rest of
  473. the paragraphs in the document.  To control this, set the variable
  474. `w3-indent-level'.  This is the number of spaces to indent lists and
  475. other items requiring special margins.
  476.  
  477.    Another thing that is easy to change about lists is the bullet
  478. character put at the front of each list item.  This is controlled by
  479. the variable `w3-list-chars-assoc', which is an assoc list.  This is a
  480. list of lists, each sublist describing what to put at the start of each
  481. particular list type.  The `car' of this list should be a symbol (not a
  482. string) representing the type of list (e.g., `ul').  The rest of the
  483. list should consist of strings to insert at certain levels of lists.
  484. The `n'th element of this list is used when the list is nested `n + 1'
  485. levels.  If the list is not long enough to define a string for a
  486. certain nesting level, then it defaults to either a '*' or a '.'.
  487.  
  488.                           -------------------
  489.  
  490.                    Formatting of directory listings
  491.  
  492.                           -------------------
  493.  
  494.    When Emacs-w3 encounters a link to a directory (whether by local
  495. file access or via ftp), it can either create an HTML document on the
  496. fly, or use `dired-mode' to peruse the listing.  The variable
  497. `url-use-hypertext-dired' controls this behavior.
  498.  
  499.    If the value is `t', Emacs-w3 uses `directory-files' to list them
  500. out and transform the directory into a hypertext document, then pass it
  501. through the parser like any other document.
  502.  
  503.    If the value is `nil', just pass the directory off to dired using
  504. `find-file'.  Using this option loses all the hypertext abilities of
  505. Emacs-w3, and the users is unable to load documents in the directory
  506. directly into Emacs-w3 by clicking with the mouse, etc.
  507.  
  508.    A new option in the 2.2 series is `url-forms-based-ftp' - this is
  509. still in the experimental stages, but can be useful.  If
  510. `url-forms-based-ftp' is `t', then all automatically generated
  511. directory listings will have a form mixed in with the file listing.
  512. Each file will have a checkbox next to it, and a row of buttons at the
  513. bottom of the screen.  Selecting one of the buttons at the bottom of the
  514. screen will take the designated action on all the marked files.
  515. Currently, only deleting and copying marked files is supported.
  516.  
  517.                           -------------------
  518.  
  519.                    Formatting of gopher directories
  520.  
  521.                           -------------------
  522.  
  523.    There are two different ways of viewing gopher links.  The built-in
  524. support that converts gopher directories into HTML, or the `gopher.el'
  525. package by Scott Snyder snyder@fnald0.fnal.gov.  The variable that
  526. controls this is `w3-use-hypertext-gopher'.  If set to `nil', then
  527. `gopher.el' is used.  Any other value causes Emacs-w3 to use its
  528. internal gopher support.  If using `gopher.el', all the hypertext
  529. capabilities of Emacs-w3 are lost.  All the functionality of
  530. `gopher.el' is now available in the hypertext version, and the
  531. hypertext version supports Gopher+ and ASK blocks.
  532.  
  533.    The main way to control the display of gopher directories is by the
  534. variable `w3-gopher-labels'.  This variable controls the text that is
  535. inserted at the front of each item.  This is an assoc list of gopher
  536. types (as one character strings), and a string to insert just after the
  537. list item.  All the normal gopher types are defined.  Entries should be
  538. similar to: `("0" . "(TXT)")'.  I have tried to keep all the tags to
  539. three characters plus two parentheses.
  540.  
  541.                           -------------------
  542.  
  543.                       Creating a horizontal rule
  544.  
  545.                           -------------------
  546.  
  547.    Horizontal rules (<HR> tags in HTML[+]) are used to separate chunks
  548. of a document, and is meant to be rendered as a solid line across the
  549. page.  Some terminals display characters differently, so the variable
  550. `w3-horizontal-rule-char' controls which character is used to draw a
  551. horizontal bar.  This variable must be the ASCII value of the character,
  552. not a string.  The variable is passed through make-string whenever a
  553. horizontal rule of a certain width is necessary.
  554.  
  555. 
  556. File: w3.info,  Node: Character based terminals,  Next: Smart terminals,  Prev: General Formatting,  Up: Controlling Formatting
  557.  
  558. On character based terminals
  559. ============================
  560.  
  561.    On character based terminals, there is no easy way to show that a
  562. certain range of text is in bold or italics.  If the variable
  563. `w3-delimit-emphasis' is non-`nil', then Emacs-w3 can insert characters
  564. before and after character formatting commands in HTML documents.  The
  565. defaul value of `w3-delimit-emphasis' is automatically set based on the
  566. type of window system and version of Emacs being used.
  567.  
  568.    Two variables control what text is inserted around different markup
  569. tags.  `w3-header-chars-assoc' controls what characters are inserted
  570. around header items, and `w3-style-chars-assoc' controls what
  571. characters are inserted around most other markup (italics, addresses,
  572. etc.).
  573.  
  574.    `w3-header-chars-assoc' is an assoc list of header tags and a list
  575. of formatting instructions.  The `car' of the list is the level of the
  576. header (1-6).  The rest of the list should contain three items.  The
  577. first item is text to insert before the header.  The second item is
  578. text to insert after the header.  Both should have reserved characters
  579. converted to their HTML[+] entity definitions.  The third item is a
  580. function to call on the area the header is in.  This function is called
  581. with arguments specifying the start and ending character positions of
  582. the header.  The starting point is always first.  To convert a region to
  583. upper case, please use `w3-upcase-region' instead of `upcase-region',
  584. so that URLs within the region are not corrupted.
  585.  
  586.    `w3-style-chars-assoc' is an assoc list of style tags and a list of
  587. strings.  The `car' of the list is the type of style tag it specifies
  588. (DFN, B, I, etc.).  The rest of the list should contain two items.  The
  589. `car' is text to insert before the stylized text.  The `cdr' is text to
  590. insert after the stylized text.  Both should have reserved characters
  591. converted to their HTML[+] entity definitions.
  592.  
  593. 
  594. File: w3.info,  Node: Smart terminals,  Next: Graphics workstations,  Prev: Character based terminals,  Up: Controlling Formatting
  595.  
  596.    If using Emacs 19.2x on a VT100 compatible terminal, Emacs-w3 can
  597. show links, headers, and various other types of emphasis in bold or
  598. underlined text.
  599.  
  600.    To do this, set the variable `w3-emacs19-hack-faces-p' to non-`nil'
  601. in your `~/.emacs' file.  Also make sure that the environment variable
  602. `TERM' is set to the correct terminal type.
  603.  
  604.    If there is a function called `w3-emacs19-hack-TERMINAL', then this
  605. is used to setup the special characters that turn on bold and
  606. underlined text.  If this function does not exist, it is fairly easy to
  607. write one from scratch, using the terminal's entry in the
  608. `/etc/termcap' file.
  609.  
  610.    Each function should use the `standard-display-table' to replace ^A,
  611. ^B, ^C, and ^D with escape sequences that turn on highlighting.  When
  612. reading the `/etc/termcap' file, be on the lookout for these codes:
  613.  
  614. `us'
  615.      Code to turn on underlining
  616.  
  617. `ue'
  618.      Code to turn off underlining
  619.  
  620. `mb'
  621.      Code to turn on boldface type
  622.  
  623. `se'
  624.      Code to turn off all attributes
  625.  
  626.    Here is an example for creating the VT100 control sequences:
  627.  
  628.      (defun w3-emacs19-hack-vt100 ()
  629.        "Hack 'faces' for ttys (vt100)"
  630.        (or standard-display-table
  631.            (setq standard-display-table (make-vector 261 nil)))
  632.        (aset standard-display-table 1 (vector (create-glyph "\e[4m")))
  633.        (aset standard-display-table 2 (vector (create-glyph "\e[m")))
  634.        (aset standard-display-table 3 (vector (create-glyph "\e[5m")))
  635.        (aset standard-display-table 4 (vector (create-glyph "\e[m")))
  636.        )
  637.  
  638.    To turn off the highlighting features, set the variable
  639. `w3-emacs19-hack-faces-p' to `nil' and execute the function
  640. `w3-emacs19-unhack-faces'
  641.  
  642.    NOTE: This highlighting is not perfect and could cause some odd
  643. display glitches, especially when Emacs does a smart redisplay and
  644. doesn't redraw the whole screen.  `C-l' usually fixes these problems.
  645.  
  646. 
  647. File: w3.info,  Node: Graphics workstations,  Next: Inlined images,  Prev: Smart terminals,  Up: Controlling Formatting
  648.  
  649. With graphics workstations
  650. ==========================
  651.  
  652.    When running in a graphic environemnt (Xwindows or NeXTstep for
  653. example), the fonts and colors used by Emacs-w3 to display text can be
  654. controlled by setting a few resources.  To specify these resources:
  655.    * Xwindows: Place them into the `~/.Xresources' file or the
  656.      `/usr/lib/X11/app-defaults/Emacs' file.
  657.  
  658.    * NeXTstep: When using the NeXTstep port of Emacs 19, use the
  659.      `dwrite' command to install these resources.  The command should
  660.      look something like: (`dwrite Emacs <Style>.Attribute<item>
  661.      value', where style and attribute are one of the choices below.
  662.  
  663.    * OS/2 or Windows: When using the Lucid Emacs or FSF Emacs that has
  664.      been ported to the Presentation Manager or Windows 3.x, the
  665.      documentation states where to store a file that Emacs looks at for
  666.      Xresources.  The resources for each version of Emacs are the same.
  667. For each style of text that Emacs-w3 uses, you can specify any of the
  668. following resources by replacing <style> with the actual style name.
  669.    * Emacs*<Style>.AttributeFont: Font name
  670.  
  671.    * Emacs*<Style>.AttributeForeground: Foreground color
  672.  
  673.    * Emacs*<Style>.AttributeBackground: Background color
  674.  
  675.    * Emacs*<Style>.AttributeUnderline: Underline text?
  676.  
  677.    Emacs-w3 uses these special style names:
  678. `w3-node-style'
  679.      For links to other documents
  680.  
  681. `w3-visited-node-style'
  682.      For displaying hypertext links that have been viewed before
  683.  
  684.    All other styles can be specified by using the tag name as the
  685. <Style> section of the resource.  For example:
  686. `Emacs*h1.attributeForeground', or `Emacs*address.attributeForeground'.
  687.  
  688. 
  689. File: w3.info,  Node: Inlined images,  Prev: Graphics workstations,  Up: Controlling Formatting
  690.  
  691.    When running in Lucid Emacs 19.10 or XEmacs 19.11 and higher,
  692. Emacs-w3 can display inlined images and MPEG movies.  There are several
  693. variables that control how and when the images are displayed.
  694.  
  695.    Since Lucid/XEmacs only natively understands XPixmaps and XBitmaps,
  696. GIFs and other image types must first be converted to one of these
  697. formats.  To do this, the netpbm utilities(1) programs are normally
  698. used.  This is a suite of freeware image conversion tools.  The
  699. variable `w3-graphic-converter-alist' controls how each image type is
  700. converted.  This is an assoc list, keyed on the MIME content-type.  The
  701. `car' is the content-type, and the `cdr' is a string suitable to pass
  702. to `format'.  A %s in this string will be replaced with a converter
  703. from the ppm image format to an XPixmap (or XBitmap, if being run on a
  704. monochrome display).  By default, the emacs-w3 browser has converters
  705. for:
  706.  
  707.   1. image/x-xbitmap
  708.  
  709.   2. image/xbitmap
  710.  
  711.   3. image/xbm
  712.  
  713.   4. image/gif
  714.  
  715.   5. image/jpeg
  716.  
  717.   6. image/x-fax
  718.  
  719.   7. image/x-raster
  720.  
  721.   8. image/windowdump
  722.  
  723.   9. image/x-icon
  724.  
  725.  10. image/portable-graymap
  726.  
  727.  11. image/portable-pixmap
  728.  
  729.  12. image/x-pixmap
  730.  
  731.  13. image/x-xpixmap
  732.  
  733.  14. image/pict
  734.  
  735.  15. image/x-macpaint
  736.  
  737.  16. image/x-targa
  738.  
  739.  17. image/tiff
  740.  
  741.    Since most displays are (sadly) not 24-bit, Emacs-w3 can
  742. automatically dither an image, so that it does not fill up the
  743. application' colormap too quickly.  If `w3-color-use-reducing' is
  744. non-`nil', then the images will use reduced colors.  If
  745. `w3-color-filter' is `eq' to `'ppmquant', then the ppmquant program
  746. will be used.  If `eq' to `'ppmdither', then the ppmdither program will
  747. be used.  The ppmdither program tends to give better results.  The
  748. values of `w3-color-max-red', `w3-color-max-blue', and
  749. `w3-color-max-green' control how many colors the inlined images can
  750. use.  If using ppmquant, then the product of these three variables is
  751. used as the maximum number of colors per image.  If using ppmdither,
  752. then only the set number of color cells can be allocated per image.
  753. See the man pages for ppmdither and ppmquant for more information on
  754. how the dithering is actually done.  `w3-color-filter' may also be a
  755. string, specifying exactly what external filter to use.  An example is:
  756. `ppmquant -fs -map ~/pixmaps/colormap.ppm'.
  757.  
  758.    When running in XEmacs 19.11 or XEmacs 19.12, Emacs-w3 can insert an
  759. MPEG movie in the middle of a buffer.  This utilizes a now deprecated
  760. feature of HTML 3.0, so its use should be limited to pages you do not
  761. mind modifying once the standard way to do this is nailed down.
  762.  
  763.    The basic syntax is:
  764.      <embed href="somevideo.mpg" type="video/mpeg">
  765.  
  766.    This requires a special version of the standard `mpeg_play' mpeg
  767. player.  Patches against the 2.0 version are available at
  768. ftp://ftp.cs.indiana.edu/pub/elisp/w3/mpeg_patch.  The variable
  769. `w3-mpeg-program' should point to this executable, and `w3-mpeg-args'
  770. should be a list of any additional arguments to be passed to the
  771. player.  By default, this includes -LOOP, so the mpeg plays
  772. continuously.
  773.  
  774.    Because images and movies can take up an incredible amount of
  775. bandwidth, it is useful to be able to control whether they are loaded
  776. or not.  By default, images and movies are loaded automatically, but
  777. the variables `w3-delay-image-loads' and `w3-delay-mpeg-loads' control
  778. this.  If set to non-`nil', then the images or movies are not loaded
  779. until explicitly requested by the user.
  780.  
  781.    To load any delayed images, use the function
  782. `w3-load-delayed-images'.  Its counterpart for delayed movies is
  783. `w3-load-delayed-mpegs'
  784.  
  785.    ---------- Footnotes ----------
  786.  
  787.    (1)  Available via anonymous ftp from
  788. ftp.x.org:/R5contrib/netpbm-1mar1994.tar.gz, and most large ftp sites.
  789.  
  790. 
  791. File: w3.info,  Node: HTTP/1.0 Support,  Next: Redirection,  Prev: Top,  Up: Top
  792.  
  793. HTTP/1.0 Support
  794. ****************
  795.  
  796.    The new revision of the HTTP specification adds much more
  797. functionality to the server side of a transaction.  Access
  798. authorization has been added, and several types of redirection can
  799. occur.  All of this negotiation and redirection should take place
  800. before the user ever sees the first requested page--this avoids the
  801. overhead of parsing any error messages or old documents the server may
  802. have returned with the redirection or authorization message.  The new
  803. protocol is also MIME (Multipurpose Internet Mail Extensions, see RFC
  804. 1341) compliant.
  805.  
  806. * Menu:
  807.  
  808. * Redirection::
  809. * Authentication::                      Accessing restricted servers and
  810.                                         documents
  811. * Payment::                             How to pay for services over the
  812.                                         World Wide Web
  813. * MIME Support::                        How Emacs-w3 uses MIME types, and
  814.                                         how to modify its behavior.
  815.  
  816. 
  817. File: w3.info,  Node: Redirection,  Next: Authentication,  Prev: HTTP/1.0 Support,  Up: HTTP/1.0 Support
  818.  
  819. Redirection
  820. ===========
  821.  
  822.    One of the most useful aspects of HTTP/1.0 is the ability to
  823. transparently move files between different servers (perhaps even
  824. different protocols).  Most of the WWW browsers support redirection in
  825. some form or another.  The Emacs browser supports all three types of
  826. redirection in the HTTP/1.0 specification (error codes 301, 302, and
  827. 303).
  828.  
  829.    Whenever a redirection response is detected, the URL specified by the
  830. Location: header is retrieved.  All relative references are resolved
  831. before requesting the new URL.
  832.  
  833.    An HTML editor that is tightly integrated with Emacs-w3 is planned,
  834. and will include the ability to edit documents to change their links if
  835. a permanent relocation is seen.
  836.  
  837. 
  838. File: w3.info,  Node: Authentication,  Next: Payment,  Prev: Redirection,  Up: HTTP/1.0 Support
  839.  
  840. Authentication
  841. ==============
  842.  
  843.    Lots of information is useful to a group of people within an
  844. organization, or a group working on a project, but it is not always wise
  845. to distribute this information to the world at large.
  846.  
  847.    The HTTP/1.0 protocol adds the capability to have authentication
  848. based on usernames and passwords.  If the improper username/password
  849. pair is sent to the server, an error code of 401, Unauthorized is
  850. returned by the server.
  851.  
  852.    The browser has a very extensible interface to its authentication
  853. handling.  When a 401 error code is received, the WWW-Authenticate
  854. header is checked--this header field should be a space-separated list
  855. of suitable authorization schemes for the requested URL.  The value of
  856. this header is read into a lisp symbol by way of Emacs's read-string
  857. function.  This lisp symbol looks like `url-authtype-auth', where
  858. authtype is replaced by the correct authorization type.  The
  859. authorization types defined in the latest HTTP/1.0 specification
  860. include user, basic, public key, and kerberos (versions 4 and 5).  If a
  861. function of this name is currently defined, then the function is called
  862. via `funcall' with several parameters:
  863.   1. The URL being authenticated.
  864.  
  865.   2. whether to prompt for a username/password if no cached data is
  866.      found.
  867.  
  868.   3. whether to overwrite an old username/password if the information is
  869.      found in the cache.
  870.         This interface was chosen for its flexibility and
  871. extensibility.  The main routine that does the MIME parsing and the
  872. building of the Authorization header does not need to know how to
  873. handle each type of authentication, and the addition of a new method
  874. for authentication is simply a matter of defining one function that
  875. conforms to a simple interface.
  876.  
  877. 
  878. File: w3.info,  Node: Payment,  Next: MIME Support,  Prev: Authentication,  Up: HTTP/1.0 Support
  879.  
  880. Payment
  881. =======
  882.  
  883.    The Chargeto: header will be used to pay for services offered over
  884. the World Wide Web.  Such things as electronic magazines and commercial
  885. databases all need a way to restrict access to only authorized
  886. subscribers.  The format of the header has yet to be specified, but the
  887. interface and storage techniques will be similar to the Authorization
  888. section.
  889.  
  890. 
  891. File: w3.info,  Node: MIME Support,  Next: Adding MIME types based on file extensions,  Prev: Payment,  Up: HTTP/1.0 Support
  892.  
  893. MIME Support
  894. ============
  895.  
  896.    MIME is an emerging standard for multimedia mail.  It offers a very
  897. flexible typing mechanism.  The type of a file/message is specified in
  898. two parts, separated by a '/'.  The first part is a general category of
  899. data (text, application, image, etc.).  The second part is the specific
  900. type of data (postscript, gif, jpeg, etc.).  So `text/html' specifies
  901. an HTML document, whereas `image/x-xwindowdump' specifies an image of
  902. an Xwindow taken with the xwd program.
  903.  
  904.    This typing allows much more flexibility in naming files.  HTTP/1.0
  905. servers can now send back content-type headers in response to a request,
  906. and not have the client second-guess it based on file extensions.  HTML
  907. files can now be named `something.gif' (not a great idea, but doable).
  908.  
  909. * Menu:
  910.  
  911. * Adding MIME types based on file extensions::  How to map file
  912.                                                 extensions onto MIME
  913.                                                 types (e.g., `.gif ->
  914.                                                 image/gif)'.
  915. * Mapping gopher types to MIME types::          Going from gopher typing
  916.                                                 to MIME types.
  917. * Specifying Viewers::  How to specify external and internal viewers
  918.                         for files that Emacs-w3 cannot handle natively.
  919. * Mailcap File::        How to set up and use a Mailcap file.  Standard
  920.                         way to specify MIME viewers - compatible with
  921.                         Mosaic and most MIME compliant mailers.
  922.  
  923. 
  924. File: w3.info,  Node: Adding MIME types based on file extensions,  Next: Mapping gopher types to MIME types,  Prev: MIME Support,  Up: MIME Support
  925.  
  926. Adding MIME types based on file extensions
  927. ------------------------------------------
  928.  
  929.    For some protocols however, it is still necessary to guess the
  930. content of a file based on the file extension.  This type of guess-work
  931. should only be needed when accessing files via FTP, local file access,
  932. or old HTTP/0.9 servers.
  933.  
  934.    Instead of specifying how to view things twice, once based on
  935. content-type and once based on the file extension, it is easier to map
  936. file extensions to MIME content-types.  The variable that controls this
  937. is `mm-mime-extensions'.
  938.  
  939.    This variable is an assoc list of file extensions and the
  940. corresponding MIME content-type.  A sample entry looks like: `(".movie"
  941. . "video/x-sgi-movie")' This makes all files that end in `.movie'
  942. (`foo.movie' and `bar.movie') be interpreted as SGI animation files.
  943. If a content-type is defined for the document, then this is
  944. over-ridden.  Regular expressions can NOT be used.
  945.  
  946.    Both Mosaic and the NCSA HTTP daemon rely on a separate file for
  947. mapping file extensions to MIME types.  Instead of having the users of
  948. Emacs-w3 duplicate this in lisp, this file can be parsed using the
  949. `url-parse-mimetypes' function.  This function is called each time w3
  950. is loaded.  It tries to locate mimetype files in several places. If the
  951. environment variable `MIMETYPES' is nonempty, then this is assumed to
  952. specify a UNIX-like path of mimetype files (this is a colon separated
  953. string of pathnames).  If the `MIMETYPES' environment variable is
  954. empty, then Emacs-w3 looks for these files:
  955.  
  956.   1. `~/.mime-types'
  957.  
  958.   2. `/etc/mime-types'
  959.  
  960.   3. `/usr/etc/mime-types'
  961.  
  962.   4. `/usr/local/etc/mime-types'
  963.  
  964.   5. `/usr/local/www/conf/mime-types'
  965.  
  966.    Each line contains information for one http type.  These types
  967. resemble MIME types.  To add new ones, use subtypes beginning with x-,
  968. such as application/x-myprogram.  Lines beginning with # are comment
  969. lines, and suitably ignored.  Each line consists of:
  970.  
  971.    type/subtype ext1 ext2 ...  extN
  972.  
  973.    type/subtype is the MIME-like type of the document. ext* is any
  974. number of space-separated filename extensions which correspond to the
  975. MIME type.
  976.  
  977. 
  978. File: w3.info,  Node: Mapping gopher types to MIME types,  Next: Specifying Viewers,  Prev: Adding MIME types based on file extensions,  Up: MIME Support
  979.  
  980. Mapping gopher types to MIME types
  981. ----------------------------------
  982.  
  983.    In order to avoid having to specify viewers for gopher in a different
  984. way, Emacs-w3 converts gopher types to MIME media types and uses the
  985. standard mailcap viewers.  The variable `url-gopher-to-mime' determines
  986. how this mapping of gopher types to MIME is done.  This is an assoc
  987. list, the `car' of each element should be a character (not a string)
  988. specifying the gopher type.  The `cdr' of each element should be a
  989. string, specifying what MIME media type the gopher object should be
  990. treated as.
  991.  
  992.    The default value for this should be sufficient for most uses, but if
  993. any gopher types have been left out, or mislabeled, please let
  994. wmperry@spry.com know.
  995.  
  996. 
  997. File: w3.info,  Node: Specifying Viewers,  Next: Mailcap File,  Prev: Mapping gopher types to MIME types,  Up: MIME Support
  998.  
  999. Specifying Viewers
  1000. ------------------
  1001.  
  1002.    Not all files look as they should when parsed as an HTML document
  1003. (whitespace is stripped, paragraphs are reformatted, and lots of little
  1004. changes that make the document look unrecognizable).  Files may be
  1005. passed to external programs or Emacs Lisp functions to be viewed.
  1006.  
  1007.    Not all files can be viewed accurately from within an Emacs session
  1008. (GIF files for example, or audio files).  For this reason, the user can
  1009. specify file "viewers" based on MIME content-types.  This is done with
  1010. the standard mailcap file.  *Note Mailcap File::
  1011.  
  1012.